Copyright (c) 1991-1993 Borland International, Inc. All Rights Reserved. THE DBASE DEBUGGER ------------------ This paper contains information about how to use the BladeRunner Debugger. TABLE OF CONTENTS ----------------- 1. Running the Debugger 2. Viewing source code and following program execution 3. Viewing program files 4. Going to a procedure 5. Going back to the current calling command (the origin) 6. Watching the stack 7. Controlling program execution a. Animating b. Stepping c. Tracing d. Setting breakpoints e. Running a program from the Debugger f. Stopping program execution g. Resetting a program 8. Watching expressions 9. Changing the values of expressions you're watching 10. Inspecting variables, objects, and arrays 11. Changing the view 12. Saving and restoring Debugger configuration 1. Running the Debugger ----------------------- You can run the Debugger in three main ways: - In the Windows Program Manager, double-click the Debugger icon - In dBASE, choose Command|Debug - In dBASE, issue the DEBUG command in the Command window or in a program file Setting any of the following debugging command switches to ON opens the Debugger: - SET STEP - SET ECHO - SET TRAP 2. Viewing source code and following program execution ------------------------------------------------------ When you're debugging a program, its source code appears in the Module window. The name of the program replaces "No Module" as the title of the window. The current command line is highlighted. As you run the program, the source code scrolls in the window to the next line receiving program control. You can scroll the source code without affecting program execution; the next command to be executed remains highlighted. 3. Viewing program files ------------------------ To view any program file, choose View|File from the Debugger menu. The Select file dialog box appears, in which you can specify the file you want to view. When you click OK or press Enter, the file appears in its own window. You can scroll the file, but you can't make changes to it in the Debugger. You need to use dBASE's Editor or another editor to modify the file. 4. Going to a procedure ------------------------ A Debugger feature that will be implemented in a future release is the capability to go to a procedure definition in the source code. When this feature is implemented, you will be able to use it by following these steps: 1. Right-click the Module window. 2. Choose Goto Proc from the Module menu that appears. 3. Type the name of the procedure in the dialog box that appears and press Enter or click OK. 5. Going back to the current calling command (the origin) --------------------------------------------------------- To return to the current command line in the source code, follow these steps: 1. Right-click the Module window. 2. Choose Origin from the Module menu that appears. The source code immediately scrolls in the Module window to bring the current command line into view. 6. Watching the stack --------------------- While you run a program in the Debugger, it keeps track of any calls the program makes to other programs, procedures, or user-defined functions (UDFs) in the Stack window. When program execution stops, the Debugger updates the Stack window. Each line in the Stack window indicates the file name and line number of subroutine calls and calling routines in the order in which they were called. You can move the Module window's focus to the location of any subroutine call by inspecting the corresponding line in the Stack window. Inspect by right- clicking the line. 7. Controlling program execution -------------------------------- The Debugger is your main tool for seeing what happens in your program. You have five main ways of controlling program execution from the Debugger: - Animating - Stepping - Tracing - Setting breakpoints - Stopping a. Animating ------------ You can animate your program from the Debugger, which gives you an opportunity to view the effects of each line. When you animate a program, the Debugger continuously executes the program, pausing at each command line and showing you the program's state at each line. Also at each line, the Debugger updates the Watch, Stack, and Module windows. To animate a program, choose Run|Animate from the Debugger menu. b. Stepping ----------- You can run a program line by line in the Debugger and control which lines to stop at. If you don't want to stop execution within a subroutine, you can step over the command line that calls the subroutine. The call to the subroutine is still made, and the subroutine is executed; you just don't see the line-by-line execution of the subroutine. The Debugger stops at the first command line following the subroutine. To step over a command line that calls a subroutine, do one of the following: - Click the Step Over icon on the SpeedBar - Choose Run|Step Over - Press F8 c. Tracing ---------- To trace into a command line that calls a subroutine means to follow the execution of each line of the subroutine. The Debugger stops at the first line of the subroutine. To trace into a command line that calls a subroutine, do one of the following: - Click the Trace Into icon on the SpeedBar - Choose Run|Trace Into - Press F7 d. Setting breakpoints ---------------------- A breakpoint is a description of a condition at which to stop program execution. That description can be one or a combination of the following: - A program location - A conditional expression - A pass count expression To set a breakpoint in your program, do any of the following: - In the Module window, move the pointer to the left of the command line to be the breakpoint and, when the pointer becomes a stop sign, click. A line describing this breakpoint appears in the Break window. You can move the pointer to the left of the command line again and click again. This removes the breakpoint. - Move the cursor to the command line to be the breakpoint and do either of the following: - Choose Break|Toggle - Press F2 A line describing this breakpoint appears in the Break window. You can choose Break|Toggle or press F2 again. This removes the breakpoint. - Choose Break|Add from the Debugger menu and enter a breakpoint expression, an action, command-line number, or a pass count expression in the Add Breakpoint dialog box. - Right-click the Break window and enter a breakpoint expression, action, command-line number, or a pass count expression in the Add Breakpoint dialog box. - Double-click an existing breakpoint line in the Break window and enter a breakpoint expression, action, command-line number, or a pass count expression in the Edit Breakpoint dialog box. The action that you can optionally specify in the Add Breakpoint and Edit Breakpoint dialog boxes is the action you want to occur when the breakpoint condition is met. e. Running a program from the Debugger -------------------------------------- You can run a program from the Debugger by doing one of the following: - Click the Run icon on the SpeedBar (the right-pointing arrow) - Choose Run|Run from the Debugger menu - Press F9 You can also specify that the program run until a RETURN command is encountered by choosing Run|Until Return. f. Stopping program execution ----------------------------- Besides adding a breakpoint, you can stop your program at any point while running it from the Debugger by doing one of the following: - Click the Stop icon on the SpeedBar (the Stop sign) - Choose Run|Stop from the Debugger menu g. Resetting a program ---------------------- If you're running a program from the Debugger and you want to stop execution and restart (reset) the program, do one of the following: - Click the Reset icon on the SpeedBar (the arrow that curves to the left) - Choose Run|Reset from the Debugger menu This reloads the program from disk. 8. Watching expressions ----------------------- Most programs contain variables for holding values and expressions that use those variables and that describe conditions. When running a program from the Debugger, you might want to watch what values get assigned to certain variables and what expressions evaluate to at certain points. Or, you might want to see what an expression using variables in the program evaluates to at certain points, even though this expression isn't in the program itself. With dBASE's Debugger, you can watch expressions, including variables, in the Watch window. To set up a watch, do one of the following: - Highlight an expression, such as a variable, or move the cursor to the expression in the source code in the Module window and do one of the following: - Right-click the expression - Choose Watch|Add - Press Ctrl+W The Add Watch dialog box appears with the expression you selected. - Choose Watch|Add from the Debugger menu and enter the expression to watch in the Add Watch dialog box. - Right-click the Watch window and enter the expression to watch in the Add Watch dialog box. - Press Ctrl+W and enter the expression to watch in the Add Watch dialog box. The expression you specify appears in the Watch window. To edit an existing watch description, - Double-click the description in the Watch window and edit it in the Edit Watch dialog box. - Choose Watch|Edit from the Debugger menu and edit the description in the Edit Watch dialog box. 9. Changing the values of expressions you're watching ----------------------------------------------------- In addition to watching the values of expressions, you can change these values. You might want to do this to change the course of a program. To change the value of an expression that you're currently watching in the Watch window, follow these steps: 1. Right-click the expression in the Watch window. 2. Choose Change from the menu that appears. 3. Enter the value you want the expression to have in the Changing "value" dialog box. The current value of the expression will already be in the dialog box. When you click OK or press Enter, the value you entered appears next to the expression in the Watch window. 10. Inspecting variables, objects, and arrays --------------------------------------------- Inspecting a variable, object, or array is different from watching them. The Debugger reevaluates a watched expression at each point program execution stops. When you establish an inspection for an expression, the Debugger preserves the value of that expression at that point of program execution. To inspect a variable, object, or array, - Highlight the expression (the variable, object, or array) or move the cursor to it in the source code in the Module window and do one of the following: - Right-click - Choose Data|Inspect - Press Ctrl+I The Inspect dialog box appears with the expression you selected. - Choose Data|Inspect from the Debugger menu and enter the expression to inspect in the Inspect dialog box. - Press Ctrl+I and enter the expression to inspect in the Inspect dialog box. When you click OK or press Enter, the Inspecting "value" dialog box appears containing the expression you entered and its value. At this point, you can right-click the expression and its value and choose from the menu that appears: - Choose Range to set a range (an upper limit and lower limit value) for the expression. The Set Range dialog box appears. - Choose Change to change the value of the expression. The Changing "value" dialog box appears. - Choose Inspect to place the selected item in its own Inspect window. - Choose Descend to descend into the layers of an object, each variable layer of which you can inspect and change. - Choose Hex Expand to view the contents of binary string variables. - Choose New Expression to inspect a different expression. The Inspect dialog box appears. You can also evaluate or modify an expression's value by choosing Data|Evaluate/Modify from the Debugger menu and entering the expression's value in the Evaluate dialog box. 11. Changing the view --------------------- To change the window focus of the Debugger, do any of the following: - Click the window you want to activate - Choose Window and then the Debugger window you want to activate - Choose View and then the operation of the window you want to activate To rearrange the windows of the Debugger, do one of the following: - Drag them by their title bars with the mouse - Change their size by dragging their borders - Minimize them by clicking their minimize buttons - Choose Window|Tile or Window|Cascade - If one or more windows is minimized, arrange their icons by choosing Window|Arrange Icons 12. Saving and restoring Debugger configuration ----------------------------------------------- Choose Options from the Debugger menu to set environment options for the Debugger and to save these settings to a .CFG file or restore options saved in an existing .CFG file. Choose Options|Options to specify which options you want to save to a .CFG file and to move the SpeedBar. The Options dialog box appears. The configuration options you can save to a .CFG file include: - Desktop (the particular arrangement of the four Debugger windows and the placement of the SpeedBar) - Application (the particular application to debug by default) - Breakpoints (the breakpoints currently set and listed in the Break window) - Watchpoints (the watchpoints currently set and listed in the Watch window) You can turn the Debugger SpeedBar off or reposition it by clicking the following buttons in the Options dialog box: - Off - Popup - Horizontal (the original setting) - Vertical To specify a default drive and directory path from which to load files into the Debugger, choose Options|Path for Sources. The Path For Sources dialog box appears, in which you can enter the default path. To save the defaults you set with the previous Options menu choices, choose Options|Save Options. The Save Configuration dialog box appears, in which you specify the name of the configuration file. The default extension is .CFG. Once you've created a configuration file, you can restore the settings you've saved to it by choosing Options|Restore Options. The Restore Configuration dialog box appears, in which you specify the name of the existing configuration file containing the settings to restore. To change the display font the Debugger uses, choose Options|Change Display Font. The Font dialog box appears, in which you can specify font preferences.